3.4 Installation and Integration
This section explains how to install and integrate the Kikobot C1 on Ubuntu 22.04 with ROS 2 Humble: flash the ESP32 controller, install kikobot-backend and Kikobot Studio, and connect your own applications over WebSocket.
1. What you are installing
The C1 control stack has two layers:
| Layer | Where it runs | What it does |
|---|---|---|
| ESP32 firmware | On-board controller (USB to PC) | Drives servos, gripper, parses serial protocol |
| Kikobot backend + Studio | Ubuntu 22.04 PC | Motion planning, RViz, WebSocket API (port 8080), optional camera |
Both C1 and C2 share the same PC packages (kikobot-backend, kikobot-studio). You select C1 at startup.
2. Hardware requirements
2.1 Robot & controller
- Kikobot C1 arm with ESP32-based servo controller
- USB cable from controller to control PC (data-capable)
- Stable mains power for arm and controller
- Emergency stop accessible before first motion
2.2 Control PC (minimum)
| Item | Requirement |
|---|---|
| OS | Ubuntu 22.04 (64-bit) |
| ROS | ROS 2 Humble (ros-humble-desktop recommended) |
| RAM | 8 GB+ (16 GB recommended with RViz) |
| Display | Required for Studio/RViz; optional for headless integration |
| USB | Free port for /dev/ttyACM0 or /dev/ttyUSB0 (typical: ACM for ESP32) |
| Network | Ethernet or Wi‑Fi for remote WebSocket clients (optional) |
2.3 Optional
- USB camera on C1 machine → MJPEG preview on port 8081 (
KIKOBOT_C1_CAMERA=1) libfuse2— required to run the Kikobot Studio AppImage
3. Download packages
Install files are listed in [FAQ and Downloads](/docs/Kikobot C1/3.6 FAQ and Downloads).
Quick links (update version on the website when you ship a new release):
| File | Download |
|---|---|
Backend (.deb) | kikobot-backend_1.0.0_amd64.deb |
| Kikobot Studio (AppImage) | kikobot-studio_1.0.0_amd64.AppImage |
| C1 ESP32 firmware (source) | c1_serial_firmware_1.0.0.zip |
4. One-time PC setup (ROS 2 Humble)
If ROS 2 Humble is not installed, follow the official ROS 2 Humble Ubuntu install, then:
sudo apt update
sudo apt install -y ros-humble-desktop
For a minimal backend (no full desktop metapackage):
sudo apt install -y ros-humble-xacro ros-humble-rviz2 ros-humble-robot-state-publisher \
ros-humble-joint-state-publisher ros-humble-joint-state-publisher-gui ros-humble-kdl-parser
Optional camera stream:
sudo apt install -y ros-humble-web-video-server
5. Install Kikobot backend (.deb)
sudo apt install -y libfuse2 python3-pip
sudo dpkg -i kikobot-backend_1.0.0_amd64.deb
If dpkg reports missing dependencies, install the packages it names (usually ROS Humble packages above), then run dpkg again. Do not run apt-get install -f if it tries to remove kikobot-backend — install missing Depends first, then:
sudo dpkg --configure -a
Verify:
kikobot-verify-backend
Installed layout:
/opt/kikobot/— ROS workspace, firmware scripts, documentationkikobot-backend— start C1 or C2 backendkikobot-install-backend— upgrade from a newer.debkikobot-verify-backend— sanity check
On-machine help: cat /opt/kikobot/CLIENT_INSTALL.txt
6. Flash ESP32 firmware (C1 only, once per controller)
The PC software does not include a pre-flashed MCU. Use the serial firmware package (recommended for current Studio/backend):
- Download c1_serial_firmware_1.0.0.zip and open
c1_serial_firmware.inoin Arduino IDE (ESP32 board support installed). - Select the correct ESP32 board and USB port.
- Set serial baud to 1 000 000 (must match PC bridge).
- Flash the controller while USB is connected to the PC.
Alternative (advanced): C1_FIRMWARE_TYPE=microros with c1_microros_firmware.ino and a micro-ROS agent — see [Software, API and ROS](/docs/Kikobot C1/3.5 Software API and ROS).
After flashing, reconnect USB. Typical device: /dev/ttyACM0.
7. USB permissions (Linux)
Ensure your user can open the serial device:
ls -l /dev/ttyACM* /dev/ttyUSB* 2>/dev/null
ls -l /dev/serial/by-id/ 2>/dev/null
If permission is denied, add your user to the dialout group (log out and back in):
sudo usermod -aG dialout "$USER"
8. First run — Kikobot Studio (recommended)
chmod +x kikobot-studio_1.0.0_amd64.AppImage
./kikobot-studio_1.0.0_amd64.AppImage
- Wait for the “Starting ROS backend” banner (~10 s on first launch).
- Select C1 as the robot model.
- Connect WebSocket: default
ws://localhost:8080(or robot PC IP from another machine). - In the UI, use Start Firmware and pick the serial port (or set
C1_SERIAL_PORT=/dev/ttyACM0before starting the backend). - Confirm joint feedback in RViz and run Home before jogging.
The AppImage can start the backend automatically; you may also run the backend separately (next section).
9. First run — backend only (integrators)
Start the C1 backend explicitly:
kikobot-backend c1
Wait for: WebSocket bridge listening on port 8080.
Headless (no RViz window):
export KIKOBOT_HEADLESS=1
kikobot-backend c1
Production (systemd):
sudo systemctl enable --now kikobot-backend@c1
sudo systemctl status kikobot-backend@c1
Environment variables (C1)
| Variable | Default | Purpose |
|---|---|---|
C1_FIRMWARE_TYPE | python | python = serial bridge; microros = micro-ROS agent |
C1_SERIAL_PORT | auto / ttyACM0 | USB serial device for ESP32 |
KIKOBOT_C1_CAMERA | 0 | Set 1 to enable MJPEG on port 8081 |
KIKOBOT_HEADLESS | unset | Set 1 to skip RViz display |
Firmware script path (override): KIKOBOT_C1_FIRMWARE_SCRIPT
Packaged default: /opt/kikobot/share/c1/kikobot_c1_firmware_bridge.py
10. Integration workflow (your application + C1)
Typical sequence without Kikobot Studio UI:
1. Install kikobot-backend .deb
2. kikobot-backend c1 (or systemd kikobot-backend@c1)
3. Your app → ws://<robot-pc-ip>:8080
4. JSON: firmware_status → start_firmware (port /dev/ttyACM0)
5. Subscribe to joint_states; send home / jog / motion_plan
Full API details: [Software, API and ROS](/docs/Kikobot C1/3.5 Software API and ROS).
Allow TCP 8080 through the firewall from integration PCs on a trusted LAN.
11. Network integration
| Service | Port | URL / notes |
|---|---|---|
| WebSocket API | 8080 | ws://<robot-pc-ip>:8080 |
| Camera (optional) | 8081 | http://<robot-pc-ip>:8081/stream?topic=/camera/image_raw |
Use the robot PC’s LAN IP when the UI or your app runs on another machine.
12. Verification checklist
| Step | Command / action | Expected result |
|---|---|---|
| Backend install | kikobot-verify-backend | Success message |
| Backend running | ss -ltn | grep 8080 | Port listening |
| WebSocket | python3 /opt/kikobot/share/examples/kikobot_ws_client_example.py --host 127.0.0.1 status | connected, robot_profile: c1 |
| Serial | start_firmware with correct port | firmware_status → running |
| Motion | Home or small jog | No fault; joints update in joint_states |
13. Logs
| Log file | Contents |
|---|---|
/tmp/kikobot_c1_display.log | RViz, motion/jog servers |
/tmp/kikobot_websocket.log | WebSocket bridge, client commands |
/tmp/kikobot_firmware.log | C1 firmware subprocess after start_firmware |
14. Upgrade & uninstall
Upgrade backend:
sudo kikobot-install-backend /path/to/kikobot-backend_1.0.0_amd64.deb
Remove backend package:
sudo apt remove kikobot-backend
Studio AppImage is portable — delete the file and optional desktop entry.
15. Related documents
- [Software, API and ROS](/docs/Kikobot C1/3.5 Software API and ROS)
- [FAQ and Downloads](/docs/Kikobot C1/3.6 FAQ and Downloads)
- See also: [Kikobot C2 installation](/docs/Kikobot C2/4.1 Installation and Integration)
Support: Replace with your published support contact (e.g. [email protected]).